Management design notes:

• The schema is checked into svn.

Todo / info to fill out:

• Gateway defintions for SNMP, JMX etc..

Management Requirements

• Must operate from a formally defined management schema.
• Must natively use the AMQP protocol and its type system.
• Must support the following operations
  • SET operation on configurable (persistent) aspects of objects
  • GET operation on all aspects of objects
  • METHOD invocation on schema-defined object-specific methods
  • Distribution of unsolicited periodic updates of instrumentation data
    • Data updates shall carry an accurate sample timestamp for rate calculation
    • Updates shall carry object create/delete timestamps.
    • Transient objects shall be fully accounted for via updates. Note that short-lived transient objects may come and go within a single update interval. All of the information pertaining to such an object must be captured and transmitted.
  • Distribution of unsolicited event and/or alert indications (schema defined)
• Role-based access control at object, operation, and method granularity
• End-to-end encryption and signing of management content
• Schema must be self-describing so the management client need not have prior knowledge of the management model of the system under management.
• Must be extensible to support the management of objects beyond the AMQP component set. This allows AMQP to be used as a general-purpose management protocol.

Architectural Framework

There are two primary interfaces defined in the management architecture:

1. The Management Console Interface is used by management clients (CLIs, GUIs, console servers, etc.) to remotely access management data.
2. The Extension Interface is used by software components (not necessarily related to the AMQP infrastructure) to provide access to their managed objects.

        +---------+    +---------+        +---------+
        |         |    |         |        |         |
        | CLI/GUI |    | Console |<======>| CLI/GUI |
        |         |    | Server  |        |         |
        +---------+    |         |        +---------+
             ^         +---------+
             |              ^
             |              |
             v              v
        +---------------------------------+
        |                                 |
        |   Managed AMQP Infrastructure   |
        |                                 |
        +---------------------------------+
                      ^
                      |
                      v
                +------------+
                |            |-+
                | Management | |-+
                | Extensions | | |
                |            | | |
                +------------+ | |
                  +------------+ |
                    +------------+

Both management interfaces are based on the AMQP protocol and its type system.

Definitions of Terms

The Management Exchange

The management exchange (called "qpid.management" currently) is a special type of exchange used for remote management access to the Qpid broker. The management exchange is an extension of the standard "Topic" exchange. It behaves like a topic exchange with the following exceptions:

1. When a queue is successfully bound to the exchange, a method is invoked on the broker's management agent to notify it of the presence of a new remote managment client.
2. When messages arrive at the exchange for routing, the exchange examines the message's routing key and if the key represents a management command or method, it routes it directly to the management agent rather than routing it to queues using the topic algorithm.
   The management exchange is used by the management agent to distribute unsolicited management data. Such data is classified by the routing key allowing management clients to register for only the data they need.

Management Message Protocol

The principals in a management exchange are the management client and the management agent. The management agent is integrated into the AMQP broker and the management client is a remote entity. A management agent may be managed by zero or more management clients at any given time. Additionally, a management client may manage multiple management agents at the same time.

For authentication and access control, management relies on the mechanisms supplied by the AMQP protocol.

Establishing Communication Between Client and Agent

Communication is established between the management client and management agent using normal AMQP procedures. The client creates a connection to the broker and then establishes a session with its corresponding channel.

Two private queues are then declared (only one if method invocation is not needed). A management queue is declared and bound to the qpid.management exchange. If the binding key is "mgmt.#", all management-related messages sent to the exchange will be received by this client. A more specific binding key will result in a more restricted set of messages being received (see the section on Routing Key Structure below).

If methods are going to be invoked on managed objects, a second private queue must be declared so the client can receive method replies. This queue is bound to the amq.direct exchange using a routing key equal to the name of the queue.

When a client successfully binds to the qpid.management exchange, the management agent schedules a schema broadcast to be sent to the exchange. The agent will publish, via the exchange, a description of the schema for all manageable objects in its control.

      Client                                                          Agent
        |                                                               |
        | --- AMQP Connection and Session Setup ----------------------> |
        |                                                               |
        | --- Queue.declare (private data queue) ---------------------> |
        | --- Bind queue to exchange 'qpid.management' key 'mgmt.#' --> |
        |                                                               |
        | --- Queue.declare (private method-reply queue) -------------> |
        | --- Bind queue to exchange 'amq.direct' --------------------> |
        |                                                               |
        | <------- Management schema via exchange 'qpid.management' --- |
        |                                                               |

Broadcast of Configuration and Instrumentation Updates

The management agent will periodically publish updates to the configuration and instrumentation of management objects under its control. Under normal circumstances, these updates are published only if they have changed since the last time they were published. Configuration updates are only published if configuration has changed and instrumentation updates are only published if instrumentation has changed. The exception to this rule is that after a management client binds to the qpid.management exchange, all configuration and instrumentation records are published as though they had changed whether or not they actually did.

      Client                                                          Agent
        |                                                               |
        | <-------------- Object Configurations via 'mgmt.config.#' --- | |
        | <--------------- Object Instrumentation via 'mgmt.inst.#' --- | |
        |                                                               | |
        |                                                               | | Publish Interval
        |                                                               | |
        |                                                               | |
        |                                                               | V
        | <-------------- Object Configurations via 'mgmt.config.#' --- |
        | <--------------- Object Instrumentation via 'mgmt.inst.#' --- |
        |                                                               |

Invoking a Method on a Managed Object

When the management client wishes to invoke a method on a managed object, it sends a method request message to the qpid.management exchange. The routing key contains the object class and method name (refer to Routing Key Structure below). The method request must have a header entry (reply-to) that contains the name of the method-reply queue so that the method response can be properly routed back to the requestor.

The method request contains a sequence number that is copied to the method reply. This number is opaque to the management agent and may be used by the management client to correlate the reply to the request. The asynchronous nature of requests and replies allows any number of methods to be in-flight at a time. Note that there is no guarantee that methods will be replied to in the order in which they were requested.

      Client                                                          Agent
        |                                                               |
        | --- Method Request (to exchange 'qpid.management') ---------> |
        |                                                               |
        |                                                               |
        | <--------------- Method Reply (via exchange 'amq.direct') --- |
        |                                                               |

Routing Key Structure

As noted above, the structure of the binding and routing keys used on the management exchange is important to the function of the management architecture. The routing key of a management message determines:

1. The type of message (i.e. operation request or unsolicited update).
2. The class of the object that the message pertains to.
3. The specific operation or update type.
4. The namespace in which the class belongs. This allows for plug-in expansion of the management schema for manageable objects that are outside of the broker itself.

Placing this information in the routing key provides the ability to enforce access control at class, operation, and method granularity. It also separates the command structure from the content of the management message (i.e. element values) allowing the content to be encrypted and signed end-to-end while still allowing access control at the message-transport level. This means that special access control code need not be written for the management agent.
There are two general types of routing/binding key:

• Command keys have the structure: method.<package>.<class>.<method> where
  • <package> is the namespace in which the <class> name is valid,
  • <class> is the name of the class as defined in the schema, and
  • <method> is one of "get", "set", or a schema-defined class-specific method name.
• Unsolicited keys have the structure: mgmt.<type>.<package>.<class>.<severity> where
  • <type> is one of "schema", "config", "inst", or "event",
  • <package> is the namespace in which the <class> name is valid, and
  • <class> is the name of the class as defined in the schema.
  • <severity> is relevant for events only. It is one of "critical", "error", "warning", or "info".

In both cases, the content of the message (i.e. method arguments, element values, etc.) is carried in the body segment of the message.

The <package> namespace allows this management framework to be extended with the addition of other software packages.

Management Message Body Structure

The body segments of management messages are composed of sequences of binary-encoded data fields, in a manner consistent with the 0-10 version of the AMQP specification.

All management messages begin with a message header:

          octet 0      1         2         3         4         5
        +---------+---------+---------+---------+---------+---------+
        |   'A'   |   'M'   |   '0'   |   '1'   | opcode  |  class  |
        +---------+---------+---------+---------+---------+---------+

The first four octets contain the protocol magic number "AM01" which is used to identify the type and version of the message.

The opcode field identifies the operation represented by the message:

The class field identifies the type of content data in a content record. If the opcode is not 'C', this field must be set to zero.

Schema Messages

Schema messages are published periodically if 1) the first instance of the object class has been created, or 2) a new management client has bound a queue to the management exchange. A schema message contains all schema-related data for a single object class.

        +-----+-----+-----+-----+-----+-----+
        | 'A' | 'M' | '0' | '1' | 'S' |  0  |
        +-----+-----+-----+-----+-----+-----+----------------------+
        |                packageName (short string)                |
        +----------------------------------------------------------+
        |                className (short string)                  |
        +----------------------------------------------------------+
        |                schema-hash (bin128)                      |
        +-----------+-----------+-----------+-----------+----------+
        | configCnt |  instCnt  | methodCnt | eventCnt  |
        +-----------+-----------+-----------+-----------+----------------------------+
        | configCnt config-element records                                           |
        +----------------------------------------------------------------------------+
        | instCnt   instrumentation-element records                                  |
        +----------------------------------------------------------------------------+
        | methodCnt method records                                                   |
        +----------------------------------------------------------------------------+
        | eventCnt  event records                                                    |
        +----------------------------------------------------------------------------+

Each config-element record is an AMQP field table with the following fields. Optional fields may optionally be omitted from the field table.

Each instrumentation-element record is an AMQP field table with the following fields:

method and event records contain a main field table that describes the method or header followed by zero or more field tables describing arguments. The main field table contains the following fields:

Argument field tables contain the following fields:

type codes are numerics with the following values:

access codes are numerics with the following values:

direction codes are numerics with the following values:

Configuration and Instrumentation Content Messages

Content messages are published when changes are made to the values of content or instrumentation elements or when new management clients bind a queue to the management exchange.

        +-----+-----+-----+-----+-----+-----+
        | 'A' | 'M' | '0' | '1' | 'C' | cls |
        +-----+-----+-----+-----+-----+-----+----------------------+
        |                packageName (short string)                |
        +----------------------------------------------------------+
        |                className (short string)                  |
        +----------------------------------------------------------+
        |                class hash (bin128)                       |
        +-----+-----+-----+-----+-----+-----+-----+-----+----------+
        | timestamp of current sample (datetime)        |
        +-----+-----+-----+-----+-----+-----+-----+-----+
        | time object was created (datetime)            |
        +-----+-----+-----+-----+-----+-----+-----+-----+
        | time object was deleted (datetime)            |
        +-----+-----+-----+-----+-----+-----+-----+-----+
        | objectId (uint64)                             |
        +-----+-----+-----+-----+-----+-----+-----+-----+------------------------+
        | config/inst values (in schema order)                                   |
        +------------------------------------------------------------------------+

All timestamps are uint64 values representing nanoseconds since the epoch (January 1, 1970). The objectId is a uint64 value that uniquely identifies this object instance.

The element values are encoded by their type into the message in the order in which they appeared in the schema message.

Method Request and Reply Messages

Method request messages have the following structure. The sequence number is opaque to the management agent. It is returned unchanged in the method reply so the calling client can correctly associate the reply to the request. The objectId is the unique ID of the object on which the method is to be executed.

        +-----+-----+-----+-----+-----+-----+
        | 'A' | 'M' | '0' | '1' | 'M' |  0  |
        +-----+-----+-----+-----+-----+-----+
        |  sequence number      |
        +-----------------------+-----------------------+
        |  objectId                                     |
        +-----------------------------------------------+------------------------+
        |  input and bidirectional argument values (in schema order)             |
        +------------------------------------------------------------------------+

Method reply messages have the following structure. The sequence number is identical to that supplied in the method request. The status code (and text) indicate whether or not the method was successful and if not, what the error was. Output and bidirectional arguments are only included if the status code was 0 (STATUS_OK).

        +-----+-----+-----+-----+-----+-----+
        | 'A' | 'M' | '0' | '1' | 'R' |  0  |
        +-----+-----+-----+-----+-----+-----+
        |  sequence number      |
        +-----------------------+
        |  status code          |
        +-----------------------+----------------------------------+
        |  status text (short string)                              |
        +-----------------------+----------------------------------+-------------+
        |  output and bidirectional argument values (in schema order)            |
        +------------------------------------------------------------------------+

status code values are:

QpidMgmtSchema.xml (text/xml)